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About This Guide 


This guide explains how to install and configure the DirXML® Driver for Manual Task Service, 
formerly the Workflow Task driver. 


The guide contains the following sections: 
+ Chapter 1, “Overview,” on page 9 
+ Chapter 2, “Upgrading,” on page 17 
+ Chapter 3, “Installing,” on page 19 
+ Chapter 4, “Configuring,” on page 21 
* Appendix A, “Replacement Data,” on page 29 
* Appendix B, “Automatic Replacement Data Items,” on page 35 
* Appendix C, “Template Action Elements Reference,” on page 37 
* Appendix D, “<mail> Element Reference,” on page 41 
* Appendix E, “Data Flow Scenario for New Employee,” on page 45 
* Appendix F, “Custom Element Handlers for the Subscriber Channel,” on page 55 
* Appendix G, “Custom Servlets for the Publisher Channel,” on page 57 
* Appendix H, “Updates,” on page 59 


Additional Documentation 


For documentation on using Nsure™ Identity Manager and the other DirXML drivers, see the 
Identity Manager Documentation Web site (http://www.novell.com/documentation/lg/dirxml20). 


Documentation Updates 


For the most recent version of this document, see the Drivers Documentation Web site (http:// 
www.novell.com/documentation/lg/dirxmldrivers). 


Documentation Conventions 


In this documentation, a greater-than symbol (>) is used to separate actions within a step and items 
within a cross-reference path. 


A trademark symbol e. TM, etc.) denotes a Novell® trademark. An asterisk (*) denotes a third-party 
trademark. 


User Comments 


We want to hear your comments and suggestions about this manual and the other documentation 
included with Identity Manager. To contact us, send e-mail to proddoc@novell.com. 
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New Feature 


Driver Features 


Overview 


This section provides an overview of the DirXML® Manual Task Service Driver, including some 
of the information necessary to successfully configure the driver. 


The Manual Task Service Driver is designed to notify one or more users that a data event has 
occurred and whether action is required from the user. In an employee provisioning scenario, the 
data event might be the creation of a new User object and the user action might include assigning 
a room number by entering data into Novell® eDirectory™ or by entering data in an application. 
Other scenarios include notifying an administrator that a new user object has been created, or 
notifying an administrator that a user has changed data on an object. 


Configuring the Manual Task Service Driver usually consists of configuring two separate but 
related subsystems: the Subscriber channel policies and e-mail templates, and the Publisher 
channel Web server templates (and possibly policies). 


In addition, driver parameters must be configured, such as SMTP server name and Web server port 
number. 


In this section: 
+ “New Features” on page 9 
+ “Modes of Operation” on page 10 


+ “How E-Mail Messages and Web Pages Are Created by the Manual Task Service Driver” on 
page 11 


+ “Templates” on page 12 

+ “Replacement Tokens” on page 14 

+ “Replacement Data” on page 14 

* “Template Action Elements” on page 15 

+ “Subscriber Channel E-Mail” on page 15 

+ “Publisher Channel Web Server” on page 16 


S 


* “Driver Features” on page 9 


* “Identity Manager Features” on page 10 


* To provide better language capabilities for e-mail messages, such as for Asian characters, 
a new XML attribute named charset can be specified on the following elements: 
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+ <mail> 


This attribute causes the header of Subject to be encoded using the specified charset (for 
example, "ISO-2022-JP"). 


+ <message> 
+ <attachment> 


If the charset attribute is specified on <message> or <attachment> elements, it overrides a 
value specified for the charset attribute on the <mail> element. 


As in previous versions of the driver, the encoding can be specified in style sheets used to 
construct the message parts, and such a specification overrides any charset attribute on 
<mail>, <message>, or <attachment>. 


+ When upgrading, existing files are preserved. 


Identity Manager Features 


For information about the new features in Nsure™ Identity Manager, see “What's New in Identity 
Manager 2?” in the Novell Nsure Identity Manager 2 Administration Guide. 


Modes of Operation 


Two primary modes of operation are supported: 


* Direct Request for Data: An e-mail message is sent requesting that a user enter data into 
eDirectory (possibly for consumption by another application). The e-mail recipient responds 
to the message by clicking a URL in the message. The URL points to the Web server running 
in the Publisher channel of the Manual Task Service Driver. The user then interacts with 
dynamic Web pages generated by the Web server to authenticate to eDirectory™ and to enter 
the requested data. 


+ Event Notification: An e-mail message is sent to a user without involving the Publisher 
channel. The e-mail message might simply be notification that something occurred in 
eDirectory, or it might be a request for data through a method other than the Publisher 
channel’s Web server, such as Novell iManager, another application, or a custom interface. 


Example: Subscriber Channel E-Mail, Publisher Channel Web Server Response 


The following is an employee provisioning example scenario in which a new employee’s manager 
assigns the employee a room number: 


1. A new User object is created in eDirectory (for example, by the DirXML driver for the 
company’s HR system). 


2. The Manual Task Service Driver Subscriber sends an SMTP message to the user’s manager 
and to the manager’s assistant. The SMTP message contains a URL that refers to the Publisher 
channel Web server. The URL also contains data items identifying the user and identifying 
those authorized to submit the requested data. 


3. The manager or the manager’s assistant clicks the URL in the e-mail message to display an 
HTML form in a Web browser. The manager or assistant then does the following: 


+ Selects the DN for his or her eDirectory User object as a means of identifying who is 
responding to the e-mail message. 


+ Enters his or her eDirectory password. 


10 DirXML Driver for Manual Task Service Implementation Guide 


* Enters the room number for the new employee. 
+ Clicks the Submit button. 


4. The room number for the new employee is submitted to eDirectory via the Manual Task 
Service Driver Publisher channel. 


Example: Subscriber Channel E-Mail, No Publisher Channel Response 


The following is an example scenario in which a new employee’s manager assigns the employee 
a computer in an asset management system: 


1. A new User object is created in eDirectory (for example, by the DirXML driver for the 
company’s HR system). 


2. The Manual Task Service Driver Subscriber sends an SMTP message to the user’s manager 
and to the manager’s assistant. The SMTP message contains instructions for entering data into 
the asset management system. 


3. The manager or assistant enters data into the asset management system. 


4. (Optional) The computer identification data is brought into eDirectory via a DirXML driver 
for the asset management system. 


How E-Mail Messages and Web Pages Are Created by the Manual 
Task Service Driver 


E-mail messages, HTML Web pages, and XDS documents can all be considered documents. The 
Manual Task Service Driver creates documents dynamically, based on information supplied to the 
driver. 


Templates are XML documents that contain the boilerplate or fixed portions of a document 
together with replacement tokens that indicate where the dynamic, or replacement, portions of the 
final, constructed document appear. 


Both the Subscriber channel and the Publisher channel of the Manual Task Service Driver use 
templates to create documents. The Subscriber channel creates e-mail messages and the Publisher 
channel creates Web pages and XDS documents. 


The dynamic portion of a document is supplied via replacement data. Replacement data on the 
Subscriber channel is supplied by the Subscriber channel policies (such as the Command 
Transformation policy). Replacement data on the Publisher channel is supplied by HTTP data to 
the Web server (both URL data and HTTP POST data). The Manual Task Service Driver can 
automatically supply certain data known to the Manual Task Service Driver (such as the Web 
server address). 


The templates are processed by XSLT style sheets. These template-processing style sheets are 
separate from style sheets used as DirXML policies in the Subscriber or Publisher channels. 


The replacement data is supplied as a parameter to the XSLT style sheet. The output of the style 
sheet processing is an XML, HTML, or text document that is used as the body of an e-mail 
message, as a Web page, or as a submission to DirXML on the Publisher channel. 


Replacement data is passed from the Subscriber channel to the Publisher channel via a URL in the 
e-mail message. The URL contains a query portion that contains the replacement data items. 
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Templates 


The Manual Task Service Driver ships with predefined style sheets sufficient to process templates 
in order to create e-mail documents, HTML documents, and XDS documents. Other custom style 
sheets can be written to provide additional processing options if desired. 


An advanced method of creating documents is also available, which uses only an XSLT style sheet 
and replacement data. No template is involved. However, this guide assumes the template method 
is used because the template method is easier to configure and maintain without XSLT 
programming knowledge. 


This section describes document creation templates as used in the Manual Task Service Driver. 


Templates are XML documents that are processed by a style sheet in order to generate an output 
document. The output document can be XML, HTML, or plain text (or anything else that can be 
generated using XSLT). 


Templates are used to generate e-mail message text on the Subscriber channel, and to generate 
dynamic Web pages and XDS documents on the Publisher channel. 


Templates contain text, elements, and replacement tokens. Replacement tokens are replaced in the 
output document by data supplied to the style sheet processing the template. 


Several examples of templates for various purposes follow. In the examples, the replacement 
tokens are the character strings that are between two $ characters and appear in bold. 


Templates can also contain action elements. Action elements are control elements interpreted by 
the template-processing style sheet. Action elements are described in Appendix C, "Template 
Action Elements Reference,” on page 37. In the following examples action elements also appear 
in bold. 


The following example template is used to generate an HTML e-mail message body: 


<html xmlns:form="http://www.novell.com/dirxml/manualtask/form"> 
<head></head> 

<body> 

Dear $manager$,<p/> 

<p> 

This message is to inform you that your new employee <b>$given-name$ 
$surname$</b> has been hired. 

<p> 

You need to assign a room number for this individual. Click <a 
href="$url$">Here</a> to do this. 

</p> 

<p> 

Thank you, <br/> 

HR Department 

</p> 

</body> 

</html> 


The following example template is used to generate a plain text e-mail message body: 


<form:text xmlns:form="http://www.novell.com/dirxml/manualtask/form"> 
Dear $manager$, 


This message is to inform you that your new employee $given-name$ $surname$ 
has been hired. 
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You need to assign a room number for this individual. Use the following link 
to do this: 


Surl$ 
Thank you, 
The HR Department 


</form:text> 


The <form:text> element is required because templates must be XML documents. The 
<form:text> element is stripped as part of the template processing. 


The following template is used to generate an HTML form used as a Web page for entering data: 


<html xmlns:form="http://www.novell.com/dirxml/manualtask/form"> 
<head> 
<title>Enter room number for $subject-name$</title> 


</head> 

<body> 
<link href="novdocmain.css" rel="style sheet" type="text/css"/> 
<br/><br/><br/><br/> 


<form class="myform" METHOD="POST" ACTION="$url-base$/ 
process template.xsl"> 
<table cellpadding="5" cellspacing="10" border="1" align="center"> 
<tr><td> 
<input TYPE="hidden" name="template" value="post_form.xml"/> 
<input TYPE="hidden" name="subject-name" value="$subject-name$"/> 


<input TYPE="hidden" name="association" value="$association$"/> 
<input TYPE="hidden" name="response-style sheet" 
value="process template.xsl"/> 
<input TYPE="hidden" name="response-template" 
value="post response.xml'"/> 
<input TYPE="hidden" name="auth-style sheet" 
value="process template.xsl"/> 
<input TYPE="hidden" name="auth-template" value="auth_response.xml"/ 


> 


<input TYPE="hidden" name="protected-data" value="$protected-data$"/> 
You are:<br/> 
<form:if-single-item name="responder-dn"> 
<input TYPE="hidden" name="responder-dn" value="$responder-dn$"/> 
$responder-dn$ 
</form:if-single-item> 
<form:if-multiple-items name="responder-dn"> 
<form:menu name="responder-dn"/> 
</form:if-multiple-items> 
</td></tr> 
<tr><td> 
Enter your password: <br/> 
<input name="password" TYPE="password" SIZE="20" MAXLENGTH="40"/> 
</td></tr> 
<tr><td> 
Enter room number for $subject-name$:<br/> 
<input TYPE="text" NAME="room-number" SIZE="20" MAXLENGTH="20" 
value="$query :roomNumber$'"/> 
</td></tr> 
<tr><td> 
<input TYPE="submit" value="Submit"/> <input TYPE="reset" 
value="Clear"/> 
</td></tr> 
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</table> 
</form> 
</body> 
</html> 


The following template is used to generate an XDS document: 


<nds> 
<input> 


<modify class-name="User" src-dn="not-applicable"> 
<association>$association$</association> 
<modify-attr attr-name="roomNumber"> 
<remove-all-values/> 
<add-value> 
<value>$room-number$</value> 
</add-value> 
</modify-attr> 
</modify> 
</input> 
</nds>s 


Replacement Tokens 


The items delimited by $ in the above example templates are replacement tokens. For example, 
$manager$ is replaced by the manager’s actual name. 


Replacement tokens can appear either in text or in XML attribute values (note the href value on 
the <a> element in the first example above). 


Replacement Data 
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Replacement data consists of strings that take the place of replacement tokens in the output 
document generated from a template. Replacement data is either supplied by Subscriber channel 
data, Publisher channel HTTP data, or it is supplied automatically by the driver. An additional type 
of replacement data is data retrieved from eDirectory via Identity Manager (query data). 
Replacement data is more fully described in Appendix A, "Replacement Data,” on page 29. 


Subscriber channel data: Subscriber channel replacement data is of two types. The first type is 
used as replacement values for replacement tokens in templates for creating e-mail messages. The 
second type is placed in the query portion of a URL so that the data is available for use on the 
Publisher channel when the URL is submitted to the Publisher’s Web server. 


HTTP data: Replacement data is supplied to the Publisher channel Web server as URL query 
string data, HTTP POST data, or both. 


Automatic data: The Manual Task Service Driver supplies automatic data. Automatic data items 
are described in Appendix B, “Automatic Replacement Data Items,” on page 35. 


Query data: Replacement tokens that start with query: are considered requests to obtain current 
data from eDirectory. The portion of the token that follows query: is the name of an eDirectory 
object attribute. The object to query is specified by one of the replacement data items 
association, src-—dn, or src-entry-id. The items are considered in the order presented in 
the preceding sentence. 
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Template Action Elements 


Action elements are namespace-qualified elements in the template that are used for simple logic 
control or that are used to create HTML elements for HTML forms. The namespace used to qualify 
the elements is http://www.novell.com/dirxml/manualtask/form. In this document and in the 
sample templates supplied with the Manual Task Service driver, the prefix used is form. 


The elements appearing in bold in the above examples are action elements. 


Action elements are described in detail in Appendix C, "Template Action Elements Reference,” 
on page 37. 


Subscriber Channel E-Mail 


The Subscriber channel of the Manual Task Service Driver is designed to send e-mail messages. 
To accomplish this, the driver supports a custom XML element named <mail>. Policies on the 
Subscriber channel construct a <mail> element in response to some eDirectory event (such as the 
creation of a user). An example <mail> element appears below: 


<mail src-dn="\PERIN-TAO\novell\Provo\Joe"> 

<to>JStanley@novell.com</to> 

<cc>carol@novell.com</cc> 

<reply-to>HR@novell.com</reply-to> 

<subject>Room Assignment Needed for: Joe the Intern</subject> 

<message mime-type="text/html"> 
<stylesheet>process_template.xsl</stylesheet> 
<template>html_msg_template.xml</template> 
<replacement-data> 


<item name=" 
<item name=" 
<item name=" 
<url-data> 


manager">JStanley</item> 
given-name">Joe</item> 
surname">The Intern</item> 


<item name="file">process template.xsl</item> 
<url-query> 


<item name="template">form template.xml</item> 
<item name="responder-dn" protect="yes">\PERIN-TAO\big-org\phb</item> 
<item name="responder-dn" protect="yes">\PERIN-TAO\big-org\carol</item> 


<item name="subject-name">Joe The Intern</item> 
</url-query> 


</url-data> 


</replacement-data> 


<resource cid="css-1">novdocmain.css</resource> 


</message> 


<message mime-type="text/plain"> 
<stylesheet>process text template.xsl</stylesheet> 
<template>txt msg template.xml</template> 
<replacement-data> 


<item name=" 


manager">JStanley</item> 


<item name=" 
<item name=" 
<url-data> 


given-name">Joe</item> 
surname">The Intern</item> 


<item name="file">process template.xsl</item> 
<url-query> 


<item 
<item 
<item 
<item 


name="template">form template.xml</item> 

name="responder-dn" protect="yes">\PERIN-TAO\big-org\phb</item> 
name="responder-dn" protect="yes">\PERIN-TAO\big-org\carol</item> 
name="subject-name">Joe The Intern</item> 


</url-query> 
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</url-data> 
</replacement-data> 


</message> 


<attachment>HR.gif</attachment> 


</mail> 


The Subscriber of the Manual Task Service Driver uses the information contained in the <mail> 
element to construct an SMTP e-mail message. A URL can be constructed and inserted into the e- 
mail message through which the e-mail recipient can respond to the e-mail message. The URL can 
point to the Publisher channel Web server or it can point to some other Web server. 


The <mail> element and its content are described in detail in Appendix D, “<mail> Element 
Reference,” on page 41. 


Publisher Channel Web Server 


The Publisher channel of the Manual Task Service Driver runs a Web server configured so that 
users can enter data into eDirectory through a Web browser. The Web server is designed to work 
in conjunction with e-mail messages sent from the Subscriber channel of the Manual Task Service 
Driver. 


The Publisher channel Web server can serve static files and dynamic content. Examples of static 
files are .css style sheets, images, etc. Examples of dynamic content are Web pages that change 
based on the replacement data contained in the URL or HTTP POST data. 


The Publisher channel Web server is normally configured to allow a user to enter data into 
eDirectory in response to an e-mail that was sent by the Subscriber channel. A typical user 
interaction with the Web server is as follows: 


1. The user submits the URL from the e-mail message to the Web server using a Web browser. 
The URL specifies the style sheet, template, and replacement data used to create a dynamic 
Web page (typically containing an HTML form). 


2. The Web server creates an HTML page by processing the template with the style sheet and 
replacement data. The HTML page is returned to the user's Web browser as the resource 
referred to by the URL. 


3. The browser displays the HTML page and the user enters the requested information. 


4. The browser sends an HTTP POST request containing the entered information as well as other 
information that originated from the e-mail URL. The DN of the user responding to the e-mail 
and the user's password must be in the POST data. 


5. The Web server authenticates the user using the user's DN and password. If the authentication 
fails, then a Web page containing a failure message is returned as the result of the POST 
request. The failure message can be constructed using a style sheet and template specified in 
the POST data. If authentication succeeds, then processing continues. 


6. The Web server constructs an XDS document using a style sheet and template specified in the 
POST data. The XDS document is submitted to Identity Manager on the Publisher channel. 


7. The result of the XDS document submission, together with a style sheet and template 
specified in the POST data, is used to construct a Web page indicating to the user the result of 
the data submission. This Web page is sent to the browser as the result of the POST request. 


16 DirXML Driver for Manual Task Service Implementation Guide 


Upgrading 


In this section: 
+ “Upgrading from the Workflow Driver to the Manual Task Service Driver” on page 17 


+ “Upgrading from the Manual Task Service Driver 1.0.1 to the Manual Task Service Driver 
1.0.2” on page 18 


Upgrading from the Workflow Driver to the Manual Task Service 
Driver 
You can install the new driver shim without affecting the existing Workflow Driver shim and 
configuration. 
1 Use the Nsure™ Identity Manager 2 installation to install the Manual Task Service Driver. 
You now have two sets of jar files, with the old names and new names. 


At this point, your existing driver configuration continues to work as it did before, using the 
Workflow Driver, because it points to the old version of the .jar files and the workflow files 
directory. 


If you want to use the new Manual Task Service Driver with your existing driver 
configuration, continue with the remaining steps in this procedure. 


2 Change the driver module name in the existing driver configuration: 
+ Previous name: com.novell.nds.dirxml.driver.workflow.driver. WorkflowDriver 
+ New name: com.novell.nds.dirxml.driver.manualtask.driver. ManualTaskDriver 


The following figure shows where to change the name. This item is the first driver parameter 
on the DirXML tab under Driver Configuration. 


Driver Module 


@ Java 
C Native 
C Connect to Remote Loader 


Name: 


Fom.novell.nds. dirxml. driver. workflow. driver. WorkflowDriver 


3 (Optional) Change the value of the driver parameter named Document Directory to use the 
new Manual Task directory. 


3a Change the directory the driver configuration is pointing to. 
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The location of this directory is platform-specific. 
For example: 

+ Previous value: C:\Novell\NDS\workflow_files 
+ New value: C:\Novell\NDS\mt_files 


3b Make sure that any driver customization that you previously made to the workflow_files 
directory is also made to the new mt_files directory. 


For example, if you have customized a template such as the e-mail template in that 
directory, make sure the same change is in the new mt_files directory as well. 


Upgrading from the Manual Task Service Driver 1.0.1 to the Manual 
Task Service Driver 1.0.2 


Installing the new driver shim automatically upgrades your existing driver, because the 1.0.1 
version of the driver refers to the same .jar file as the 1.0.2 version of the driver. Similarly, your 
changes to the mt_files directory, such as customizing templates, are preserved, and the 1.0.2 
version of the driver points to the same directory as the 1.0.1 version did. 


If you are using the driver to send e-mail in languages other than English, consider using the new 
charset attribute, described in "New Features” on page 9. 
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Installing 


+ Installation: The DirXML* Driver for Manual Task Service is automatically installed when 
you install the DirXML Server using the Nsure™ Identity Manager installation program. See 
“Installation” in the Novell Nsure Identity Manager 2 Administration Guide. 


¢ Platforms: The driver runs on the platforms supported by Identity Manager and the Remote 
Loader. See “Identity Manager Components and System Requirements” in the Novell Nsure 
Identity Manager 2 Administration Guide. 


* Activation: The driver does not require separate activation; when you activate the DirXML 
engine, this driver is also activated. See “Activating Identity Manager Products” in the Novell 
Nsure Identity Manager 2 Administration Guide. 
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Configuring 


This section describes configuring Manual Task Service Driver parameters and templates. 


Driver Parameters 


Driver Settings 


This section describes parameters that appear in the "Driver Settings” section in the driver object 
user interface. 


Many of these parameters are actually for the Publisher channel Web server. They appear under 
the Driver Settings area because the Manual Task Service Driver Subscriber also needs access to 
them. 


DN of the Document Base 


This parameter is an eDirectory DN of a container object. The Manual Task Service Driver can 
load XML documents (including XSLT style sheets) from eDirectory as well as from disk. If XML 
documents should be loaded from eDirectory, this parameter identifies the root container from 
which documents are loaded. 


Documents loaded from eDirectory reside in the attribute value of an eDirectory object. If 
unspecified, the attribute is XmlData. The attribute can be specified by appending a # character 
followed by the attribute name to the name of the object containing the document. 


For example, suppose that the document base DN is specified to be “novell\Manual Task 
Documents” and that there is a container under “Manual Task Documents” named “templates.” 


Ifa DirXML-Style Sheet object named “e-mail template” resides under the “templates” directory, 
then the following resource identifiers can be used to refer to the XML document: “templates/e- 
mail template” or “templates/e-mail _template#Xm1Data”’. 


The resource identifiers can be supplied as replacement data, URL data, or HTTP POST data. For 
example, the following element might appear under a <message> element on the Subscriber 
channel: 


<template>templates/e-mail _template#XmlData</template> 


Document Directory 


This parameter identifies a file system directory that is used as the base directory for locating 
resources such as templates, XSLT style sheets, and other file resources served by the Publisher 
channel Web server. Example values are: 


Windows c:\Novell\Nds\mt_files 
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NetWare SYS:ASYSTEM\mt_files 


UNIX lusr/lib/dirxml/rules/manualtask/mt_files 


Use HTTP Server (true|false) 


This parameter indicates whether the Publisher channel should run a Web server or not. Set the 
parameter to true if the Web server should be run or false if the Web server should not be run. 


If the Manual Task Service Driver is only to be used for sending e-mail with no response URL, or 
with a URL that points to another application, then the HTTP server should not be run, to save 
system resources. 


HTTP IP Address or Host Name 


HTTP Port 


Name of KMO 


This parameter allows you to specify on which of multiple, local IP addresses the Publisher 
channel Web server will listen for HTTP requests. 


Leaving the HTTP IP address or host name parameter value blank causes the Publisher channel 
Web server to listen on the default IP address. For servers with a single IP address, this is sufficient. 
Placing a dot-notation IP address as the parameter value causes the Publisher channel Web server 
to listen for HTTP requests on the address specified. 


Note that the value specified for HTTP IP address or host name is used by the Subscriber channel 
mail handler to construct URLs if the host name or address 1s not specified in the mail command 
element. If the parameter Use HTTP server (true|false) is set to false, then HTTP IP address or host 
name can be used to specify the address or name of a Web server to use in constructing URLs for 
mail messages. 


This parameter is an integer value indicating which TCP port the Publisher channel Web server 
should listen on for incoming requests. If this value is not specified, the port number defaults to 80 
or 443, depending on whether or not SSL is being used for the Web server connections. 


If the Manual Task Service Driver is running on the Nsure™ Identity Manager server (that is, it is 
not being run under the Remote Loader on a remote machine) then the HTTP port should be set to 
something other than 80 or 443. This is because iMonitor or another process is typically using ports 
80 and 443. 


If it is not blank, this parameter is the name of an eDirectory Key Material Object that contains the 
server certificate and key used for SSL by the Publisher channel Web server. 


Setting this parameter causes the Publisher channel Web server to use SSL for servicing HTTP 
requests. 


This parameter takes precedence over any Java* keystore parameters (see below). 


Using SSL is recommended for security reasons because eDirectory passwords are passed in 
HTTP POST data when using the Publisher channel Web serve 
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Name of Keystore File 


This parameter, together with Keystore password, Name of certificate(key alias), and Certificate 
password (key password), is used to specify a Java keystore file that contains a certificate and key 
used for SSL by the Publisher channel Web server. 


Setting this parameter causes the Publisher channel Web server to use SSL for servicing HTTP 
requests. 


If the Name of KMO parameter is set, then this parameter and its associated parameters are 
ignored. 


Using SSL is recommended for security reasons because eDirectory passwords are passed in 
HTTP POST data when using the Publisher channel Web server. 

Keystore Password 
This parameter specifies the password for the Java keystore file specified with the Name of 
keystore file parameter. 

Name of Certificate (key alias) 
This parameter specifies the name of the certificate to use in the Java keystore file specified with 
the Name of keystore file parameter. 

Certificate Password (key password) 


This parameter specifies the password for the certificate specified using the Name of certificate 
(key alias) parameter. 


Subscriber Settings 


SMTP Server 
This parameter specifies the name ofthe SMTP server that the Subscriber channel will use to send 
e-mail messages. 

SMTP Account Name 


If the SMTP server specified using the SMTP server parameter requires authentication then this 
parameter specifies the account name to use for authentication. The password used is the 
Application password associated with the driver Authentication parameters. 


Default *From” Address 


If specified, this is an e-mail address used in the SMTP from field for e-mail messages sent by the 
Subscriber channel. If this is not specified, then the <mail> elements sent to the Subscriber must 
contain a <from> element. 


A <from> element under <mail> elements sent to the Subscriber overrides this parameter. 


Additional Handlers 


If specified, then this is a whitespace-separated list of Java class names. Each class name is a 
custom class that implements the com.novell.nds.dirxml.driver.manualtask.CommandHandler 
interface and handles a custom XDS element. (The handler for <mail> is a built-in handler). 
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Additional information about custom handlers is available in Appendix F, *Custom Element 
Handlers for the Subscriber Channel,” on page 55. 


Publisher Settings 


Additional Servlets 


If non-blank, this is a whitespace-separated list of Java class names. Each class name is a custom 
class that extends javax.servlet.http.HttpServer. Custom servlets can be used to extend the 
functionality of the Publisher channel Web server. 


Additional information about custom servlets is available in Appendix G, “Custom Servlets for the 
Publisher Channel,” on page 57. 


Subscriber Channel Policies 


The configuration of the Subscriber channel policies depends on what a particular installation 
wants to accomplish with the Manual Task Service Driver. However, there are certain guidelines 
that might be helpful. 


In general, the best place to construct a <mail> element to send to the Subscriber is in the 
Command Transformation policy. The reason for this is that most DirXML engine processing has 
been completed by the time commands reach the Command Transformation policy. This means 
that Create Policies have been processed for add events (allowing vetoing of add events for objects 
that don’t have all the attributes necessary for constructing the e-mail, for example). This also 
means that modify events for objects without associations have already been converted to add 
events. 


The XSLT style sheet that constructs the e-mail message might or might not need to query 
eDirectory for additional information. 


For example, if the e-mail message is simply a welcome message to a new employee, then the add 
command can contain all the information necessary: Given Name, Surname, and Internet E-mail 
Address. This is accomplished by specifying in the Create policy that Given Name, Surname, and 
Internet E-mail Address are required attributes. This ensures that only add commands that contain 
the necessary information can reach the Command Transformation. 


However, if the e-mail message is a message to the manager of an employee, then the style sheet 
needs to query eDirectory. The manager DN can be obtained from the add event for the employee’s 
User object, but a query must be made to obtain the manager’s e-mail address because that 
information is an attribute of the manager’s User object. 


In addition, if e-mail notifications are being generated as the result of modify commands for 
objects that are associated with the driver, then queries must be made to obtain information not 
contained in the modify command. 


Blocking Commands from Reaching the Subscriber 


If e-mail messages are to be generated from events other than add events, then add events must be 
allowed to reach the Subscriber for those objects that are to be monitored. Allowing add events to 
reach the Subscriber results in a generated association value being returned to Identity Manager 
from the Subscriber. 


24 DirXML Driver for Manual Task Service Implementation Guide 


It is important that eDirectory objects to be monitored by the Manual Task Service Driver policies 
have an association for the Manual Task Service Driver. Only objects that have an association will 
have delete, rename, and move events reported to the driver. In addition, modify events on objects 
that do not have an association are converted to add events after the Subscriber channel event 
transformation. 


All other commands (modify, move, rename, and delete) should be blocked by the Command 
Transformation policy and prevented from reaching the Subscriber. The Subscriber handles only 
<add> commands and <mail> commands. Other commands result in the Subscriber returning an 
error. 


Generating E-Mail Messages 


E-mail messages are sent by the Subscriber in response to receiving a <mail> element that 
describes the e-mail message to be sent. See Appendix D, “<mail> Element Reference,” on 
page 41 for a description of the <mail> element and its content. 


E-mail messages can be generated in response to any Identity Manager event (add, modify, 
rename, move, delete). 


The replacement data that is supplied with the <message> element children of a <mail> element 
depends on two primary factors: 


* The template used to generate the message body. Replacement items to be used by the e-mail 
template appear as children of the <replacement-data> element. 


* The information needed by the Web page templates on the Publisher channel if the e-mail is 
to result in a response on the Publisher channel. Replacement items to be used by the Web 
page templates appear as children of the <url-query> element, which is a child of <url-data>, 
which in turn is a child of <replacement-data>. 


If the e-mail message should contain a URL that points to the Publisher channel Web server and 
is used to solicit information from a user, then the replacement data must contain at least one 
responder-dn item. The values of the responder-dn items must be the DNs of the User objects of 
the users to which the message is being sent. 


If a query replacement token (see “Replacement Data” on page 14) is used in the template, then 
the replacement data for the <message> element must contain an item named src-dn, src-entry-id, 
or association with the appropriate value. An association item can only be used if the eDirectory 
object to be queried already has an association for the Manual Task Service Driver. The association 
generated by the Subscriber for unassociated objects cannot be used because it hasn’t been written 
to the eDirectory object when the query takes place. 


The <message> element can specify the MIME type of the message body. If the MIME type is 
specified but a style sheet is not specified (that is, there is no <stylesheet> element child of 
<message>) then one of two default style sheet names is used. If the MIME type is text/plain, the 
default style sheet name is process text template.xsl. Ifthe MIME type is anything other than text/ 
plain, the default style sheet name is process_template.xsl. 


Subscriber Channel E-Mail Templates 


E-mail templates are XML documents containing boilerplate and replacement tokens. E-mail 
templates are used to generate e-mail message body text. See “Templates” on page 12 for general 
information about templates. 
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The replacement tokens used in an e-mail template dictate the <item> elements that must be 
supplied as children of the <replacement-data> element that is constructed by the Subscriber 
channel policy that constructs the <mail> element. For example, if the e-mail template has the 
replacement token $employee-name$ then there must be an <item name="employee-name”> 
element in the replacement data for the <message> element. If the employee name item is not 
present, the resulting e-mail message body has no text in the location occupied by the replacement 
token in the template. 


E-mail templates can be used to generate message bodies that are plain text, HTML, or XML. 


If an e-mail template generates a plain text message, it must be processed by a style sheet that 
specifies plain text as its output type. If the style sheet does not specify plain text as its output type, 
then undesirable XML escaping will occur. The default Manual Task Service Driver style sheet, 
process_text_template.xsl, is normally used for processing templates that result in plain text. 


Publisher Channel Policies 


In most implementations of the Manual Task Service Driver, no Publisher channel policies are 
needed. This is because is it possible to construct the Web page and XDS templates so they result 
in exactly the XDS required and the XDS need not be further processed by policies. 


If policies are required they will be very specific to an installation. 


Publisher Channel Web Page Templates 


Web page templates are XML documents containing boilerplate and replacement tokens. Web 
page templates are used to generate Web page documents (typically HTML documents). See 
“Templates” on page 12 for general information about templates. 


Replacement tokens in Web page templates dictate what replacement data is supplied as URL 
query data on the Subscriber channel. Replacement data on the Publisher channel is obtained from 
the URL query string for HTTP GET requests and from the URL query string and the POST data 
for HTTP POST requests. 


As an example of the flow of replacement data from the Subscriber channel to the e-mail message 
and then to the Publisher channel Web server, consider the following scenario. 


The Manual Task Service Driver is configured so that a new employee”s manager is asked to assign 
a room number to the new employee. The trigger for the e-mail to the manager is the <add> 
command for a new User object that is processed by the Subscriber channel Command 
Transformation policy. 


When the manager clicks a URL in the e-mail message, a Web page is displayed in the manager *”s 
Web browser. The Web page must indicate for whom the manager is entering a room number. 


To accomplish this, the <url-query> element on the Subscriber channel contains a replacement 
data item that identifies the new user by name: 


<item name="subject-name”>Joe the Intern</item> 


This causes the URL query string to contain (among other things) “subject- 
name=Joe%20the%20Intern”. (The *%20” is a URL-encoded space). 


The manager’s Web browser submits the URL to the Publisher channel Web server when the 
manager clicks the URL in the e-mail message. The Web server constructs a replacement data item 
named subject-name with the value Joe the Intern. 
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The Web page template also specified by the URL contains a replacement token $subject-name$. 
When the Web page template is processed by the style sheet to construct the Web page, the 
replacement token is replaced by Joe the Intern, which customizes the Web page for the employee 
whose User object creation caused the e-mail to be sent. 


For additional information on a complete Subscriber-channel-to-Publisher-channel transaction, 
see Appendix E, "Data Flow Scenario for New Employee,” on page 45. 


Publisher Channel XDS Templates 


XDS templates are XML documents containing boilerplate and replacement tokens. XDS 
templates are used to generate XDS documents that are submitted to Identity Manager on the 
Manual Task Service Driver’s Publisher channel. See Templates under the Overview section for 
general information about templates. 


Replacement tokens in XDS templates dictate some of the replacement data that is supplied to the 
Web server as data in an HTTP POST request. 


For example, consider the following XDS template: 


<nds> 
<input> 
<modify class-name="User" src-dn="not-applicable"> 
<association>$association$</association> 
<modify-attr attr-name="roomNumber"> 
<remove-all-values/> 
<add-value> 
<value>$room-number$</value> 
</add-value> 
</modify-attr> 
</modi fy> 
</input> 
</nds> 


The replacement tokens in the template dictate that the HTTP POST data must supply an 
association value and a room-number value. 


Normally the association value would originate in the Subscriber channel. The Subscriber channel 
e-mail would place association=some value in the query string of the URL that is placed in the e- 
mail message. The Web page template used to generate the Web page when the URL is submitted 
to the Web server would typically place the association value in a hidden INPUT element: 


<INPUT TYPE="hidden" NAME="association" VALUE="Sassociation$"/> 


Placing the association value as a hidden INPUT element causes the “association=some value” 
pair to be submitted as part ofthe HTTP POST data. 


The room-number value is entered in the Web page using an INPUT element similar to the 
following: 


<input TYPE="text" NAME="room-number" SIZE="20" MAXLENGTH="20"/> 


If the manager enters 1234 and clicks Submit, the Web browser sends “room-number=1234” as 
part of the HTTP POST data. 


The Web server then generates an <item name="association”> replacement data item and an <item 
name="room-number”> replacement data item which are used when processing the XDS 
template. 
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Trace Settings 
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The XDS document is generated by processing the XDS template with the style sheet specified in 
the POST data. Then the XDS document is submitted to Identity Manager on the Manual Task 
Service Driver’s Publisher channel. 


The Manual Task Service Driver outputs messages with various trace levels: 


Level 


0 


1 


Trace Message Description 

No trace messages 

Single-line messages tracing basic operation 

No additional messages (DirXML Engine traces XML documents at this level and above) 
No additional messages 

Messages relating to document construction from templates and style sheets 


Replacement data documents traced 
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Replacement Data 


Replacement data is used with XML documents used as templates to construct e-mail messages, 
Web pages, and XDS documents. The actual replacement is accomplished by processing the 
template document with an XSLT style sheet that performs the replacement as part of constructing 
the output document. 


Replacement data is supplied to the Manual Task Service Driver through different mechanisms on 
the Subscriber and Publisher channels. 


Subscriber Channel 
* Replacement data is supplied as part of the <mail> element. 


* Part of the supplied replacement data can be URL data. If URL data is supplied, it is processed 
and completed and replaced by automatic data items (see Appendix B, *Automatic 
Replacement Data Items,” on page 35). 


* Ifthe <mail> element specifies that an association value should be constructed (that is the 
<mail> element has a src-dn attribute) then an automatic data item named “association” is 
added to the replacement data. 


Publisher Channel 
* Replacement data is supplied in the HTTP URL data and HTTP POST data. 


* Automatic URL replacement data items are added to the replacement data before it is used in 
template processing. 


Replacement data is presented during template processing as an XML document. The replacement 
data document is passed to the style sheet processing the template as a parameter named 
replacement-data. If no template is used, the XML document is processed directly by the style 
sheet. 


Data Security 


Data items are passed from the Subscriber channel to the Publisher channel via a URL contained 
in the e-mail sent by the Subscriber channel. Changing certain data items in the URL represents a 
security threat. For example, if the responder-dn values in the URL supplied by the Subscriber 
channel in the URL are replaced by another user’s DN in the URL submitted to the Publisher 
channel Web server, it would allow an unauthorized user to change data in eDirectory. 


To ensure that the data in the submitted URL is the same as the data originally supplied by the 
Subscriber channel, protected data is provided. Protected data is data that cannot be changed for 
security reasons. This data varies by configuration but always includes the responder-dn data 
items, and data items corresponding to any eDirectory objects whose values are to be changed. 


Data items are protected by encrypting the original values and placing the encrypted values into a 
URL query string. When the Publisher Web server receives the encrypted values, the Publisher 
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decrypts the values and uses them to compare the unencrypted data items that are supplied by an 
HTTP GET or POST request. 


If an instance of a data item appears in the encrypted data, then an unencrypted data item value 
must match one of the encrypted data item values. If the unencrypted data item value does not 
match one of the encrypted data item values, then the HTTP request is rejected by the Publisher 
channel Web server. 


In addition, any HTTP POST request that does not contain protected data is rejected. 


Example 


In an HTTP POST request, the Publisher channel Web server uses the unencrypted POST data 
named responder-dn to check the password supplied by the POST data. This is done to authenticate 
the responding user against the user’s eDirectory object. 


Suppose the Subscriber channel <url-query> element content specifies two data items as follows: 


<item name="responder-dn" protect="yes">\PERIN-TAO\novell\phb</item> 


<item name="responder-dn" protect="yes">\PERIN-TAO\novell\carol</item> 
P 


The URL generated by the Subscriber channel will contain both responder-dn values in the 
protected data. 


Suppose a malicious user obtains the URL that is generated and sent in an e-mail message. The 
malicious user uses the URL to obtain the HTML form that allows users to change data for an 
eDirectory object. 


In the HTTP POST request that is submitted to the Web server, the malicious user uses his 
eDirectory DN (responder-dn=\PERIN-TAO\novell\wally) as the unencrypted responder-dn 
value. The malicious user also submits his own password in the POST data so that the 
authentication that the Web server performs will succeed. 


However, when the Publisher channel Web server receives the HTTP POST data, it fails to find 
“\PERIN-TAO\novell\wally” in the encrypted protected data and rejects the POST request. 


XML Elements 


The elements that make up a replacement data document are described below. If no XML attributes 
are described for an element, then none are allowed. 


<replacement-data> 
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The <replacement-data> element can appear in the following locations: 
1. As a child of the <message> element under a Subscriber channel <mail> element. 


The Manual Task Service Driver processes the supplied <replacement-data> element into a 
standalone <replacement-data> element for use in template processing. The following 
processing occurs: 


a. If an association value is created for the enclosing <mail> element, an <item 
name="association”> element is added to the replacement data. The value of the created 
element is the association value that is returned to Nsure™ Identity Manager. 
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<item> 


<item> attributes 


b. If the <replacement-data> element has a <url-data> element child, then the <url-data> 
element is replaced by several <item> elements that contain constructed URL data. See 
<url-data> and <url-query>. 


2. As the standalone top-level element of a replacement data document used when constructing 
a document using a style sheet on either the Subscriber or the Publisher channels. 


The <item> element can be a child of the <replacement-data> element, the <url-data> element, or 
the <url-query> element. The content of the <item> element is the text used in the substitution of 
replacement tokens in templates. <item> elements are always named using the name attribute. 


name: The value of the name attribute specifies the name by which this data item is referenced by 
replacement tokens. For example, if the value of the name attribute is manager, then the 
replacement token $manager$ is replaced by the value contained by <item name="manager”> 
element. The name attribute is required. 


protect: For <item> elements that are children of <url-query> elements, the protect attribute 
specifies whether the item is added to the protected data section of the URL query string (see <url- 
query>. If the protect attribute is present, it must have the value yes. 


Predefined <item> names 


Certain <item> elements have predefined meanings to either the Subscriber channel, the Publisher 
channel, or both channels. 


template: The Publisher channel treats the value of the template item as the name of the template 
document to use in generating the response to an HTTP GET request. 


When <item name="template”> appears as a child of the <url-query> element on the Subscriber 
channel, the value is placed into the URL query data to specify to the Publisher channel Web server 
the name of the template document to use when responding to the HTTP GET request. 


responder-dn: The Publisher channel uses the value of the responder-dn item in HTTP POST data 
as the DN of the eDirectory object against which the password supplied in the HTTP POST data 
is validated. 


The Web server rejects any HTTP POST request that does not contain a responder-dn value and a 
password value. In addition, if the HTTP POST data does not contain a protected-data item, then 
the request is rejected. 


The Subscriber channel supplies one or more <item name="responder-dn” protect="yes”> 
elements under the <url-query> element. Because the responder-dn items are used for user 
authentication, the items must be protected. 


password: Supplied to the Publisher channel Web server via HTTP POST data. The item content 
is the password, which is validated against the eDirectory object specified by the responder-dn 
item in the POST data. The password item is normally entered in the HTML form used to generate 
the HTTP POST request. 


Example: 


<INPUT TYPE= "password" NAME="password" SIZE="20" MAXLENGTH="40"/> 
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<url-data> 


response-template: Supplied to the Web server via HTTP POST data. Used to generate the Web 
page used as the response to the POST. The response-template item is normally specified using a 
hidden INPUT element in the HTML form used to generate the HTTP POST request. 


Example: 


<INPUT TYPE="hidden" NAME="response-template" VALUE="post form.xml"/> 


response-stylesheet: Supplied to the Web server via HTTP POST data. Used to generate the Web 
page used as the response to the POST. The response-stylesheet item is normally specified using 
a hidden INPUT element in the HTML form used to generate the HTTP POST request. 


Example: 


<INPUT TYPE="hidden" NAME="response-stylesheet" 
VALUE="process template.xsl"/> 


auth-template: Supplied to the Web server via HTTP POST data. Used to generate the Web page 
that is used as the response to the POST if authentication of the user fails. The auth-template item 
is normally specified using a hidden INPUT element in the HTML form used to generate the HTTP 
POST request. 


Example: 


<INPUT TYPE="hidden" NAME="auth-template" VALUE="auth_response.xml"/> 


auth-stylesheet: Supplied to the Web server via HTTP POST data. Used to generate the Web page 
that is used as the response to the POST if authentication of the user fails. The auth-template item 
is normally specified using a hidden INPUT element in the HTML form used to generate the HTTP 
POST request. 


Example: 


<INPUT TYPE="hidden" NAME="auth-stylesheet" VALUE="process template.xsl"/> 


protected-data: The protected-data item contains the encrypted data constructed by the 
Subscriber channel. On the Subscriber channel, the protected data item is an automatically 
supplied item. 


On the Publisher channel, the protected-data item is obtained from the URL query string for an 
HTTP GET request and is obtained from the POST data for an HTTP POST request. 


The protected data item is typically passed from the HTTP GET request into the Web page used 
to generate the HTTP POST via a replacement token in the template used to construct the response 
to the HTTP GET. 


Example: 


<INPUT TYPE="hidden" NAME="protected-data" VALUE="Sprotected-data$"/> 


The <url-data> element is a child of the <replacement-data> element found under the <message> 
element on the Subscriber channel. It contains <item> elements used to construct the URL and 
related data items that are supplied to the template used in constructing the e-mail message. It also 
contains the <url-query> element. 


For the purposes of the Manual Task Service driver, URLs consist of five parts: 
1. A scheme such as http, https, or ftp. 
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2. A host such as www.novell.com or 192.168.0.1. 
3. A port number. This is a colon followed by a decimal integer. For example, :80 or :8180. 


4. A file or resource specifier. This is typically a filename and can include path information. For 
example, stylesheets/process_template.xsl. 


5. A query string. This is a collection of name-value pairs, separated by & characters. For 
example, template=form_template.xml&protected-data=AabABJKEL= 


Predefined <item> Names Under <url-data> 


<url-query> 


<item> elements under the <url-data> element are ignored unless they are one of the following. 
All of them are optional. 


file: Specifies the file portion of the URL. If used with the Publisher channel Web server, the file 
item specifies the style sheet to use to construct the initial HTML page returned in response to the 
URL. If used with a server other than the Publisher channel Web server, the file item specifies the 
name of the resource that the URL will refer to. 


If the file item does not appear, the URL file portion defaults to process_template.xsl. 


scheme: Optional item found under the <url-data> element. If present, it specifies the scheme 
portion of the URL (such as http or ftp). The scheme item is typically used only if the URL points 
at a server other than the Publisher’s Web server. 


If the scheme item does not appear, the URL scheme defaults to either http or https, depending on 
the configuration of the Publisher channel Web server. 


host: Optional item found under the <url-data> element. If present, specifies the host portion of 
the URL. The host item is typically used only if the URL were to point at a server other than the 
Publisher’s Web server. 


If the host item does not appear, the URL host defaults to the IP address of the server on which the 
Manual Task Service Driver is running (that is, the IP address of the Publisher channel Web 
server). 


port: Optional item found under the <url-data> element. If present, specifies the port portion of 
the URL. The port item is typically used only if the URL points at a server other than the 
Publisher’s Web server. 


If the port item does not appear, the URL port defaults to the port on which the Publisher channel 
Web server is running. 


The <url-query> element is a child of the <url-data> element. It contains <item> elements that are 
used to construct the query portion of the URL used in the e-mail message. 


Each item that appears as a child of the <url-query> element is placed in the query string in the 
form name="value” where name is the value of the <item> element’s name attribute and value is 
the string content of the <item> element. 


Item elements that appear under <url-query> can have a protect attribute with the value “yes.” If 
this is the case, then the item names and values are encrypted and placed within a generated name- 
value pair in the URL query string. The name of the generated value is protected-data. The value 
is the Base64 encoded and encrypted name-value pair or pairs for multivalued attributes. 
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Protecting data ensures that the data cannot be changed when the URL is submitted to the 
Publisher channel Web server. For example, the responder-dn data items need to be protected to 
ensure that only those users authorized to respond to the e-mail message are able to change 
eDirectory data. 


Ifthe URL generated is to be used with the Publisher channel Web server, the <url-query> element 
must contain at least one <item name="responder-dn” protect="yes”> element or the Web server 
rejects the eventual HTTP POST request. 
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Automatic Replacement Data Items 


The Manual Task Service Driver automatically supplies certain replacement data item elements. 
This section describes those data items. 


Subscriber Channel Automatic Replacement Data 


The following data items are added automatically to replacement-data documents during 
processing by the Subscriber channel: 


association: An <item name=”association”> element is added to the replacement-data document 
if the <mail> element has an <association> element child, or if the Subscriber returns an <add- 

association> element. The content of the <item> element is the association value for the eDirectory 
object that is associated with the e-mail message being processed. The association value might not 
yet be written to the eDirectory object; therefore, the association value cannot be used in queries. 


url: The content of the <item> element is the complete URL to be used in the e-mail message. On 
the Subscriber channel, the url item is created from the following items found under the <url-data> 
element: scheme, host, port, file, and the items underneath the <url-query> element. If scheme, 
host, or port are not found, then default values are used. The default values are determined from 
the configuration of the Publisher channel Web server. 


url-base: The content of the <item> element is the portion of the generated URL not including the 
resource identifier (file) and not including the query string. 


url-query: The content of the <item> element is a URL query string generated from <item> 
elements underneath the <url-query> element. 


url-file: The content of the <item> element is the resource identifier for the URL. 


protected-data: The content of the <item> element is an encrypted form of name-value pairs 
obtained from <item> elements under the <url-query> element. Only <item> elements whose 
protect attribute is set to “yes” are added to the protected data value. See Data Security in 
Appendix A, “Replacement Data,” on page 29 for more information about protected data. 


Publisher Channel Automatic Replacement Data 


The following data items are automatically added to replacement-data documents during 
processing by the Publisher channel Web server: 


post-status: An <item name="post-status”> element is created and added to the replacement-data 
document by the Publisher channel Web server during the processing of an HTTP POST request. 
An HTTP POST request to the Web server is a request to submit an XDS document to Nsure™ 
Identity Manager. Identity Manager returns a status document as the result ofthe XDS submission. 
The content of the <item name="post-status”> element is the value of the level attribute of the 
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<status> element that is returned by Identity Manager as the result of the submission to Identity 
Manager. 


The post-status item is typically used in the construction of the Web page that is returned as the 
result of the HTTP POST request. 


post-status-message: An <item name="post-status-message”> element is created and added to 
the replacement-data document by the Publisher channel Web server during the processing of an 
HTTP POST request. An HTTP POST request to the Web server is a request to submit an XDS 
document to Identity Manager. Identity Manager returns a status document as the result of the XDS 
submission. The content of the <item name="post-status-message”> element is the content of the 
<status> element that is returned by Identity Manager as the result of the submission to Identity 
Manager. The post-status-message item is created only ifthe <status> element returned by Identity 
Manager has content. 


The post-status-message item is typically used in the construction of the Web page that is returned 
as the result of the HTTP POST request. 


url: An <item name="url”> element is created and added to the replacement-data document by the 
Publisher channel Web server during processing of HTTP GET and HTTP POST requests . The 
<item> element is added before using the replacement-data document to construct any documents. 
The URL scheme, host, and port are determined by the Web server configuration. 


url-base: An <item name="url-base”> is created and added to the replacement data document by 
the Publisher channel Web server during processing of HTTP GET and HTTP POST request. The 
<item> element is added before using the replacement-data document to construct any documents. 
The content of the url-base <item> element on the Publisher channel is the same as the url <item> 
element. 
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Template Action Elements Reference 


Action elements are namespace-qualified elements in a template document that are used for simple 
logic control or are used to create HTML elements for HTML forms. The namespace used to 
qualify the elements is http://www.novell.com/dirxml/manualtask/form. In this document and in 
the sample templates supplied with the Manual Task Service driver the prefix used is form. 


Any action element not specifically covered in this section is stripped from the output document 
by the template-processing style sheet (unless the style sheet is customized). This behavior allows, 
for example, the use of a form:text element to enclose the data for a plain text e-mail message, 
thereby making the template valid XML. 


<form:input> 


The <form:input> element is used to generate one or more HTML INPUT elements based on the 
presence of one or more replacement data items. The number of INPUT elements created 
corresponds with the number of replacement data items with the name specified by the 
<form:input> element’s name attribute. 


Attributes 


Name: Specifies the name of the replacement data items that are used to create the INPUT 
elements. The attribute value is used as the value of the name attribute of the created INPUT 
elements. 


type or TYPE: Specifies the value of the type attribute of the created INPUT elements. 


value: If the value attribute’s value is equal to “yes,” then a value attribute is added to the created 
INPUT elements whose value is the string value of the replacement data item. If the value 
attribute’s value is other than “yes,” then the content of the created INPUT elements is set to the 
string value of the replacement data item. 


Example 
<form: input name="responder-dn” TYPE=“hidden” value="yes”/> 
creates one or more INPUT elements similar to 


<INPUT name="responder-dn” TYPE=“hidden” value=“\PERIN-TAO\novell\phb”/> 


<form: if-item-exists> 
The <form:if-item-exists> element is used to conditionally insert data into the output document. 


The content of <form:if-item-exists> is processed only if the specified item appears in the 
replacement data. 


Template Action Elements Reference 37 


Attributes 


Name: Specifies the name of the replacement data item. If one or more examples of the 
replacement data item exist, then the contents of the <form:if-item-exists> element are processed. 


Example 


<form:if-item-exists name="post-status-message"> 
<tr> 
<td> 
Status message was: S$post-status-message$ 
</td> 
</tr> 
</form:if-item-exists> 


This example inserts a row into an HTML table only if there is a replacement data item named 
post-status-message. 


<form:if-multiple-items> 


The form:if-multiple-items element is used to conditionally insert data into the output document. 
The content of form:if-multiple-items is processed only if the specified item appears more than 
once in the replacement data. 


Attributes 


name: Specifies the name of the replacement data item. If more than one example of the 
replacement data item exists, then the content of the form:if-multiple-items is processed. 


Example 


<form:if-multiple-items name="responder-dn"> 
<form:menu name="responder-dn"/> 
</form:if-multiple-items> 


This example builds an HTML SELECT element (see <form:menu>) if there is more than one 
replacement data item with the name responder-dn. 
<form:if-single-item> 


The form:if-single-item element is used to conditionally insert data into the output document. The 
content of form:if- single -item is processed only if the specified item appears exactly once in the 
replacement data. 


Attributes 


name: Specifies the name of the replacement data item. If the named item appears exactly once in 
the replacement data, then the content of the form:if-single-item is processed. 


Example 


<form:if-single-item name="responder-dn"> 
<input TYPE="hidden" name="responder-dn" value="Sresponder-dn$"/> 
$responder-dn$ 

</form:if-single-item> 
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This example inserts an HTML INPUT element and some replacement text into the output 
document if there is exactly one replacement data item named “responder-dn” in the replacement 
data. 


<form:menu> 


The form:menu element is used to generate an HTML SELECT element with one or more 
OPTION element children. The first OPTION element child is marked as selected. 


Attributes 


name: Specifies the name of the replacement data item. If the named item appears in the 
replacement data, then an HTML SELECT element is created in the output document. An HTML 
OPTION element is created as a child of the SELECT element for each instance of the replacement 
data item in the replacement data. 


Example 


<form:menu name="responder-dn"/> 


This example results in HTML elements similar to the following: 


<SELECT name="responder-dn"> 

<OPTION selected>\PERIN-TAO\big-org\php</OPTION> 
<OPTION>\PERIN-TAO\big-org\carol</OPTION> 
</SELECT> 
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<mail> 


<to> 


<cc> 


<bcc> 


<from> 


<mail> Element Reference 


The <mail> element and its content are described in detail in this section. If no attributes are listed 
for an element, then that element has no attributes defined. 


The <mail> element and its content describe the data necessary to construct an SMTP message. 


<mail> attributes 


sre-dn: Contains the DN value of the eDirectory object that is triggering the e-mail. Required if 
the object’s data is to be modified via the Publisher channel’s Web server in response to the e-mail. 


The <to> element is a child of the <mail> element. One or more <to> elements contain the e-mail 
addresses of the primary recipients of the SMTP message. At least one <to> element is required. 
Each <to> element must contain only a single e-mail address. 


The <cc> element is a child of the <mail> element. Zero or more <cc> elements contain the e-mail 
addresses of the CC recipients of the SMTP message. No <cc> element is required. Each <cc> 
element must contain only a single e-mail address. 


The <bcc> element is a child of the <mail> element. Zero or more <bcc> elements contain the e- 
mail addresses of BCC recipients of the SMTP message. No <bcc> element is required. Each 
<bcc> element must contain only a single e-mail address. 


The <from> element is a child of the <mail> element. The <from> element contains the e-mail 
address of the sender of the e-mail . The <from> element is not required. If the <from> element is 
not present, then the default from address supplied as part of the Manual Task Service Driver 
parameters is used. 
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<reply-to> 


<subject> 


<message> 


The <reply-to> element is a child of the <mail> element. The <reply-to> element contains the e- 
mail address of the entity to which replies to the SMTP message will be addressed. The <reply- 
to> element is not required. 


The <subject> element is a child of the <mail> element. Its string content is used to set the SMTP 
subject field. The <subject> element is not required but is recommended, for obvious reasons. 


The <message> element is a child of the <mail> element. Its content is used to construct a message 
body for the SMTP message. At least one <message> element is required. Multiple <message> 
elements can be supplied when constructing an SMTP message with alternative representations of 
the message body (such as plain text and HTML, or English and another language). 


<message> attributes 


mime-type: Optionally specifies the MIME type of the message body constructed by the 
<message> element (such as text/plain or text/html). If the mime-type attribute is not present, the 
driver attempts to automatically discover the MIME type. 


E-mail clients can use the MIME type when an SMTP message has alternative representations in 
order to choose the best representation to display. 


language: Optionally specifies the language of the message body constructed by the <message> 
element. The value should follow the SMTP specification. If the language attribute is not present, 
no default is supplied. 


E-mail clients can use the language specification when an SMTP message has alternative 
representations in order to choose the best representation to display. 


<stylesheet> 


<template> 


<filename> 


The <stylesheet> element is a child of the <message> element. The content of the <stylesheet> 
element is the name of an XSLT style sheet used to construct the message body. If the <stylesheet> 
element is not present, then process_template.xsl is used as the style sheet. 


The <template> element is a child of the <message> element. The content of the <template> 
element is the name of an XML document used to construct the message body. If the <template> 
element is not present, then the replacement data document is processed by the message style sheet 
to construct the message body. 


The <filename> element is a child of the <attachment> element. The content of the <filename> 
element is a filename. The filename value is used to assign a filename to a constructed attachment. 
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<replacement-data> 


The <replacement-data> element is a child of the <message> element. Its content is used either as 
a parameter to the style sheet processing the message template, or in the absence of a template, it 
is processed directly by the message style sheet. The contents of the <replacement-data> element 
are described in Appendix A, “Replacement Data,” on page 29 and Appendix B, “Automatic 
Replacement Data Items,” on page 35. 


<resource> 


The <resource> element is a child of the <message> element. Its content is treated as the name of 
a file to be incorporated into the SMTP message a resource for the message body. For example, a 
.css style sheet for an HTML message body could be supplied as a resource. 


<resource> attributes 


cid: Specifies the content ID used to refer to the resource in URLs in the message body. For 
example, if a .css style sheet is the resource, then the cid value might be css-1. In the HTML 
message body the following element can be used to refer to the .css style sheet: 


<link href="cid:css-1" rel="style sheet" type="text/css"> 


<attachment> 


The <attachment> element is a child of the <mail> element. It can have the same content as 
<message>, or it can have a filename as content. Zero or more <attachment> elements can appear 
as children of the <mail> element. 


<attachment> attributes 


mime-type: Optionally specifies the MIME type of the attachment. If the mime-type attribute is 
not present, the driver will attempt to automatically discover the MIME type. 


language: Optionally specifies the language of the attachment. If the language attribute is not 
present, no default is supplied. 
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Data Flow Scenario for New Employee 


This section gives a step-by-step examination of the data flow in an example situation when hiring 
a new employee causes an e-mail message to be sent to the employee’s manager. The e-mail 
message requests that the manager use a URL in the message to enter a room number value for the 
employee. 


The configuration of the Manual Task Service Driver is as follows for the example scenario. 


Subscriber Channel Configuration 


Filter 
Class: User 


Attributes: Given Name, manager, Surname 


Policies 
Create policy: Requires Given Name, manager, and Surname attributes. 


Command Transformation policy: Converts the <add> into the <mail> element. 


Publisher Channel Configuration 


Filter 
Class: User 


Attributes: roomNumber 


Policies 


None. 


Description of Data Flow 


In the following list, the most important data items that flow through the process are responder-dn 
and association. The responder-dn item is used to authenticate the user entering data through the 
Web server. The association item identifies the eDirectory object whose data is to be changed. 


1. The company hires a new employee. The new employee’s data is entered into the company’s 
Human Resource (HR) system. 


2. The DirXML driver for the HR system creates a new User object in eDirectory. User attributes 
include Given Name, Surname, and manager. 
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3. The following <add> event for the new User object is submitted to the Manual Task Service 
Driver Subscriber channel: 


<nds dtdversion="1.1" ndsversion="8.6"> 
<input> 
<add class-name="User" src-—dn="\PERIN-TAO\novell\Provo\Joe" src- 
entry-id="281002" timestamp="1023314433#2"> 
<add-attr attr-name="Surname"> 
<value type="string">the Intern</value> 
<add-attr> 
<add-attr attr-name="Given Name"> 
<value type="string">Joe</value> 
<add-attr> 
<add-attr attr-name="manager"> 
<value type="dn">\PERIN-TAO\novell\Provo\phb</value> 
<add-attr> 
</add> 
</input> 
</nds> 


a. The Subscriber Command Transformation policy uses the manager DN value to issue a 
query to eDirectory for the manager’s e-mail address and the manager’s assistant’s DN. 


b. If the manager has an assistant, the Subscriber Command Transformation issues a query 
to eDirectory for the assistant’s e-mail address. 


c. The Subscriber Command Transformation constructs a <mail> element and replaces the 
<add> command element with the <mail> element. In the example below, replacement 
data items are in bold. 


<nds dtdversion="1.1" ndsversion="8.6"> 
<input> 
<mail src-dn="\PERIN-TAO\novell\Provo\Joe"> 
<to>phb@company.com</to> 
<cc>carol@company.com</cc> 
<bcc>HR@company.com</bcc> 
<reply-to>HRQcompany.com</reply-to> 
<subject>Room Assignment Needed for: Joe the Intern</subject> 
<message mime-type="text/html"> 
<stylesheet>process_template.xsl</stylesheet> 
<template>html_msg_template.xml</template> 
<replacement-data> 
<item name="manager">JStanley</item> 
<item name="given-name">Joe</item> 
<item name="surname">the Intern</item> 
<url-data> 
<item name="file">process template.xsl</item> 
<url-query> 


<item name="template">form template.xml</item> 
<item name="responder-dn" protect="yes">NPERIN- 
TAO\novell\Provo\phb</item> 
<item name="responder-dn" protect="yes">NPERIN- 
TAO\novell\Provo\carol</item> 
<item name="subject-name">Joe the Intern</item> 
</url-query> 
</url-data> 
</replacement-data> 
<resource cid="css-1">novdocmain.css</resource> 
</message> 
</mail> 
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</input> 
</nds> 


. The Manual Task Service Driver Subscriber receives the <mail> element from Nsure™ 
Identity Manager. 


. The Subscriber generates an association value because the <mail> element has a src-dn 
attribute. 


. The Subscriber constructs a replacement data document from the data in the <mail> 
element for use in constructing the e-mail message. The URL has various data items in 
the query portion (that portion of the URL that follows the *?” character and is in bold). 
The Publisher channel Web server uses these data items when the URL is submitted to 
the Web server as an HTTP GET request. 


<replacement-data> 
<item name="manager">JStanley</item> 


<item name="given-name">Joe</item> 

<item name="surname">the Intern</item> 

<item name="template">form template.xml</item> 

<item name="responder-dn">\PERIN-TAO\novell\Provo\phb</item> 
<item name="responder-dn">\PERIN-TAO\novell\Provo\carol</item> 
<item name="subject-name">Joe the Intern</item> 


<item name="association">1671b2:ee4246a561:-7fff:192.168.0.1</item> 
<item name="url-base">https://192.168.0.1:8180</item> 
<it name="url-file">process template.xsl</item> 


<item name="protected-data"> 
rO0ABXNyABlgYXZheC5jcenlwdG8uU2VhbGVKkT2JqZWNOPjY9ps03VHACAARbAA 
11bmNvZGVkUGFyYW1lzdAACWOJLbABBl1bmNyeXBOZWRDb250ZW50cO0B+AAFMAA1w 
YXJhbXNBbGdOABJMamF2YS9sYW5SnLINOcmluZztMAAdzZWFsQWxncQB+AAJ4cH 
VyAAJbQqzzF/gGCFTgAgAASHAAAAAPMAOECE IBRONGP jxEAgEKdXEAfgAEAAAA 
uMSF qzHXwtMx8DkRCzkK1046sEz1lu5lo3MDvHn+3+fE6SphHr3Hg3j1i4Jp3rUk 
H7y6dXvcu7iq21Vs+906iZVzlijTIJX/3jjRrVZIR5SJOuURNhkSJHFZ8FhgsmiIAH 
/Fs61k4WmyEcmYfWmfqfBVeThr3Avwcim6ranS5Mm2U5i9Z/DBR13pIAobMpWY 
kMaz4+G9e600vBsiPdp6jSPzbFxcgALI2AMBh4hf9jnx7zOU9Uvd9qXtaE2rRO 
AANQOKVOABBOOkKVXaXRoTUQ1LQW5kKREVT</item> 

<item name="url-query">template=form template.xml&amp;responder- 
dn=%5CPERIN-TAO%5Cnovell%5Cprovo%5Cphb&amp; responder-dn=%5CPERIN- 
TAO%$5Cnovell%5Cprovo%5Ccarol&amp; subject- 
name=Joe+the+Intern&amp;association=1671b2%3Aee4246a561%3A— 
7£££$3A192.168.0.1&amp;protected- 
data=r00ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVkT2JqZWNOPjY9ps03VHACAARbAA1l 
lbmNvZGVKUGFyYW1zdAACWOJbABBIbmNyeXBOZWRDb250ZW50cQ0B%2BAAFMAAlwYXJhb 
XNBbGdOABUMamF 2YS9sYW5nL1NOcm1uZztMAAdzZWF sQWxncQB%S2BAAJ4cHVyAAJbOqz 
zFS2FgGCFTgAgAAeHAAAAAPMAOECEIBRohGP j xEAGEKAXEAfgARAAAAUMSF qzHXwtMx8 
DkRCzZkK104 6sEz1u5103MDVHn%2B3%2BfE6SphHr3Hgjli4Jp3rukH7y6dxXvcu7ig21V 
s%2B906iZVzljTIJX%2FjJJRrVZIRSJOURNhk8JHFZ8FhgsmilAHs2FFs6l1k4WmyEcmYf 
WmfqfBVeThr3AvwciméranS5Mm2U5i9Z%2FDBRI3pIAobMpWYkMaz4%2BG9e600vBsiP 
dp6jSPzbFxcgALI2AMBh4hf9jnx7zOU9Uvd9qXtaE2rROAANQOOKVOABBOOKVXaXROoTUQ 
1Q0W5KREVT</item> 

<item name="url"> 
https://192.168.0.1:8180/ 
process template.xsl?template=form template.xml&amp; responder- 
dn=%5CPERIN-TAO%5Cnovell%5CProvo%5Cphb&amp; responder-dn=%5CPERIN- 
TAO%5Cnovell%5Cprovo%5Ccarol&amp; subject- 
name=Joe+the+Intern&amp;association=1671b2%3Aee4246a561%3A- 
7£££%$3A192.168.0.1&amp; protected- 
data=r00ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVkT2JqZWNOP jY 9psO3 VHACAARbDAA1 
lbmNvZGVkUGF yYW1 zdAACWOJbABB1bmNyeXB0 ZWRDb250ZW5 0cOB%2BAAFMAAIwYXJhb 
XNBbGdOABJMamF2YS9sYW5SnLINOcmluZztMAAdzZWFsQWxncQB%2BAAJ4cHVyAAJbQqz 
zF%2FgGCFTgAgAAeHAAAAAPMAOECEIBRohGP jxEAgEKdXEAfgAEAAAAUMSFqzHXwtMx8 
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DKRCzkK1046sEzlu5lo3MDvHn%2B3%2BfE6SphHr3Hgjli4Jp3rUkH7y6dXveu7iq21V 
s%2B906iZVz1jTIJXS2F3jRrVZlR5JouRNhk8JHFZ8FhgsmilAHS$2FFs61k4WmyEcmY £ 
WmfqfBVeThr3Avwcim6ranS5Mm2USi9Z%2FDBR13pIAobMpWYkMaz4%2BG9e60ovBsiP 
dp6jSPzbFxcgALI2AMBhA4hf9jnx7zO0U9Uvd9qXtaE2rROAANQQKVOABBOQKVXaXRoTUQ 
1OW5kREV 

</item> 

</replacement-data> 


. The Subscriber processes html msg template.xml with process template.xsl. The 


replacement data document is passed as a parameter to the style sheet. The 

html msg template.xml document follows. Note the replacement tokens in bold. The 
replacement tokens are replaced by the value of the corresponding <item> elements in 
the replacement data document. 


<html xmlns:form="http://www.novell.com/dirxml/manualtask/form"> 
<head> 
</head> 
<body> 
<link href="cid:css-1" rel="style sheet" type="text/css"/> 
<p> 
Dear $manager$, 
</p> 
<p> 


This message is to inform you that your new employee <b>$given- 
name$ $surname$</b> has been hired. 

</p> 

<p> 

Please assign a room number for this individual. Click <a 
href="$url$">Here</a> to do this. 

</p> 

<p> 

Thank you, <br/> 

HR<br/> 

HR Department 

</p> 

</body> 

</html> 


The generated e-mail document follows. The replacement tokens have been replaced 
with the values of the corresponding <item> elements from the replacement data 
document. 


<html> 
<head> 
<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
</head> 
<body> 
<link href="cid:css-1" rel="style sheet" type="text/css"> 
<p> 


Dear J Stanley, 

</p> 

<p> 

This message is to inform you that your new employee <b>Joe the 
Intern</b> has been hired. 

</p> 

<p> 

Please assign a room number for this individual. Click <a 
href="https://192.168.0.1:8180/ 
process_template.xsl?template=form_template.xml&responder 
dn=%5CPERIN-TAO%5Cnovell%5CProvo%5Cphb&responder-dn=%5CPERIN- 
TAO%$5Cnovell%5CProvo%5Ccarol&subject- 
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name=Joe+the+Internsassociation=45f0e3%3Aee45e07709%3A- 
7£££$3A192.168.0.1&protected- 
data=rO00ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVkT2JqZWNOPjY9ps03VHACAARbAA1l 
lbmNvZGVKUGFyYW1zdAACWOJbABBIbmNyeXBOZWRDb250ZW50cQ0B%2BAAFMAAlwYXJhb 
XNBbGAdOABJMamF2YS9sYWSnLINOCmluZztMAAdzZWFsQOWxncQB%2BAAJ4cHVyAAJbOqz 
ZF$2FgGCFTgAgAASHAAAAAPMAOECIr9Z1iG%2BO3BAGEKAXEAfgAEAAAAUMUS2FSOFRK 
ebvh2d5SqalF91lttjRYSLyyW5%2B%2FFIfOuDdYikYiDbOJb6607S0dPHjQzeVgu6ptI 
vGqaEQOEjBjJDkY%2Bi4VOVjUSXS3a8fiXB8moMdPtLJ%2FGyE8QiwbT4xbkOy48i02Kk9 
9F2vGmlenRpSP6dD31kZl3dpJ0OmGgq2yL%2FeFaynKyqgnjkHLMexcqD8WlVooaRllik2R 
Pk5vDYvC802bn22O0KKbOnNSRMSY1PS0iWzxo0JVenVVyt OAANOOKVOABBOOKVXaXROTUQ 
1QWSKREVT">Here</a> to do this. 

</p> 

<p> 

Thank you, <br> 

HR<br> 

HR Department 

</p> 

</body> 

</html> 


h. The SMTP e-mail message is sent to the manager and to the manager’s assistant. 


i. The Subscriber returns an XML document containing a <status> element and an <add- 
association> element to Identity Manager. 


4. The manager opens the e-mail message and clicks the “Click here” link. 


5. The manager’s Web browser submits the URL to the Publisher channel Web server as an 
HTTP GET request. 


a. The Web server constructs the following replacement data document. Most of the data 
items come from the query portion of the URL. The exceptions are the automatically 
generated items url and url-base. 


<replacement-data> 

<item name="association">45f0e3:ee45e07709:-7fff:192.168.0.1</item> 

<item name="protected- 
data">rO0ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVKkT2JqZWNOPjY9ps03VHACAARbAA 
11bmNvZGVkUGFyYW1lzdAACWOJLbABB1bmNyeXBOZWRDb250ZW50cOB+AAFMAA1wYXJhbX 
NBbGdOABJUMamF 2YS9sYW5nL1INOcmluZztMAAdz ZWF sOQWxncQBt+AAJ4 cHVyAAJbOQOqzzF/ 
gECFTgAgAASHAAAAAPMAOECIr9Z1iG+03BAgEKAXEAfgAEAAAAUMU/ 
SoFRkebvh2d5SqalF91ttjRY5lyyW5+/ 
FifouDdYikYiDbOJb6607S0dPHjQzeVgu6ptIvGqaEQOEjBjDkY+i4VOVjUSXS3a8fiX 
B8moMdPt LJ/GyE8QiwbT4xbkOy48i02k99F2vGmlenRpSP6dD31kZ13dpJ0mGgq2yL/ 
eFaynKyqnjkHLMexcqD8W1VooaR11k2RPk5vDYvC802bn220KKbOnSRM5Y1PS0iWzxo0 
JVcnVVyt OAANOOKVOABBOOKVXaXRoTUO1O0W5kREVT</item> 

<item name="template">form template.xml</item> 

<item name="responder-dn">\PERIN-TAO\novell\Provo\phb</item> 

<item name="responder-—dn">\PERIN-TAO\novell\Provo\carol</item> 

<item name="subject-name">Joe the Intern</item> 

<item name="url-base">https://192.168.0.1:8180</item> 

<item name="url">https://192.168.0.1:8180</item> 
</replacement-data> 


The Web server processes the form templates.xml document with the 

process template.xsl style sheet. Replacement tokens and action elements are in bold. 
Note that various data items are placed in hidden INPUT elements so that the data items 
are passed to the Web server as part of the HTML POST data. 


In addition, there is a $query:roomNumber$ replacement token, which retrieves the 
current value of the employee’s roomNumber attribute (if any). 
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<html xmlns:form="http://www.novell.com/dirxml/manualtask/form"> 


<head> 
<title>Enter room number for $subject-name$</title> 

</head> 

<body> 
<link href="novdocmain.css" rel="style sheet" type="text/css"/> 
<br/><br/><br/><br/> 


<form class="myform" METHOD="POST" ACTION="$url-base$/process template.xsl"> 


MAXLI 


<table cellpadding="5" cellspacing="10" border="1" align="center"> 
<tr><td> 
<input TYPE="hidden" name="template" value="post_form.xml"/> 
<input TYPE " name="subject-name" value="$subject-name$"/> 
<input TYPE="hidden" name="association" value="$association$"/> 
<input TYPE="hidden" name="response-style sheet" value="process template.xsl"/> 
<input TYPE="hidden" name="response-template" value="post response.xml"/> 
<input TYPE="hidden" name="auth-style sheet" value="process template.xsl"/> 
<input TYPE="hidden" name="auth-template" value="auth response.xml"/> 
<input TYPE="hidden" name="protected-data" value="S$protected-data$"/> 
<form:if-single-item name="responder-dn"> 
You are:<br/> 
<input TYPE="hidden" name="responder-dn" value="Sresponder-dn$"/> 
$responder-dn$ 
</form:if-single-item> 
<form:if-multiple-items name="responder-dn"> 
Indicate your identity:<br/> 
<form:menu name="responder-dn"/> 
</form:if-multiple-items> 
</td></tr> 
<tr><td> 
Enter your password: <br/><input name="password" TYPE="password" SIZE="20" 
ENGTH="40"/> 
</td></tr> 
<tr><td> 
Enter room number for $subject-name$:<br/> 
<input TYPE="text" NAME="room-number" SIZE="20" MAXLENGTH="20" 


i 
5 
2 
5 


dd dd BE 


value="S$query: roomNumber$ " /> 


</td></tr> 
<tr><td> 
<input TYPE="submit" value="Submit"/> <input TYPE="reset" value="Clear"/> 
</td></tr> 
</table> 
</form> 
</body> 
</html> 
The following HTML page is the result: 
<html> 
<head> 
<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
<title>Enter room number for Joe the Intern</title> 
</head> 
<body> 
<link href="novdocmain.css" rel="style sheet" type="text/css"> 
<br><br><br><br> 
<form class="myform" METHOD="POST" ACTION="https://192.168.0.1:8180/ 
process template.xsl"> 
<table cellpadding="5" cellspacing="10" border="1" align="center"> 
<tr> 
<td> 
<input TYPE="hidden" name="template" value="post form.xml"> 
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<input TYPE="hidden" name="subject-name" value="Joe the Intern"> 


<input TYPE="hidden" name="association" value="45f0e3:ee45e07709: 
7£££:192.168.0.1"> 
<input TYPE="hidden" name="response-style sheet" 
value="process_template.xsl"> 
<input TYPE="hidden" name="response-template" 
value="post_response.xml"> 
<input TYPE="hidden" name="auth-style sheet" 
value="process_template.xsl"> 
<input TYPE="hidden" name="auth-template" 


value="auth_response.xml"> 


<input TYPE="hidden" name="protected-data" 
value="r00ABXNyABlqYXZheC5jcenlwdG8uU2VhbGVKkT2JqZWNOPjY9ps03VHACAARbA 
AllbmNvZGVKUGFyYWI1zdAACWOJbABBlbmNyeXBOZWRDb250ZW50cQB+AAFMAAlwYXJhb 
XNBbGAdOABJMamF2YS9sSYWSnLINOcmluZztMAAdzZWFsQOWxncQOB+AAJ4cHVyAAJbOqzzF 
/ gGCF TgGAgAAeHAAAAAPMAOECIr9Z1iG+tO3BAgEKdXEA f gAEFAAAAUMU/ 
SoFRkebvh2d5SqalF91ttjRY5lyyW5+/ 
FIfOuDdYikYiDbOJb6607S0dPHjQzeVgu6pt IvGqaEQOEjBjDkY+i4VOVjUSXS3a8fiX 
B8moMdPt LJ/GyE8QiwbT4xbkOy48i02k99F2vGmlenRpSP6dD31kZ13dpJ0mGgq2yL/ 
eFaynKyqnjkHLMexcqD8W1VooaR11k2RPk5vDYvC802bn220KKbOnSRM5Y1PS0iWzxo0 
JVcnVVyt OAANOOKVOABBOOKVXaXRoTUQ1OW5KREVT"> 

Indicate your identity:<br> 

<SELECT name="responder-dn"> 
<OPTION selected>\PERIN-TAO\novell\Provo\phb</OPTION> 
<OPTION>\PERIN-TAO\novell\Provo\carol</OPTION> 

</SELECT> 
</td> 
</tr> 
<tr> 
<td> 
Enter your password: <br> 


<input name="password" TYPE="password" SIZE="20" MAXLENGTH="40"> 
</td> 
</tr> 
<tr> 
<td> 
Enter room number for Joe the Intern:<br> 
<input TYPE="text" NAME="room-number" SIZE="20" MAXLENGTH="20" 
value=""> 
</td> 
</tr> 
<tr> 
<td> 
<input TYPE="submit" value="Submit"> <input TYPE="reset" 
value="Clear"> 
</td> 
</tr> 
</table> 
</form> 
</body> 
</html> 


. The manager selects his or her eDirectory DN from the Web page menu, enters the 
password, enters the room number for the new employee, and clicks Submit. 


. The Web browser submits an HTTP POST request to the Web server. 


. The Web server constructs the following replacement data document from the POST 
data. Note the data that was in the various hidden <INPUT> elements. The data entered 
by the manager in the form is in bold. 
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<replacement-data> 

<item name="room-number">cubicle 1234</item> 

<item name="template">post form.xml</item> 

<item name="response-template">post response.xml</item> 

<item name="auth-template">auth response.xml</item> 

<item name="association">45f0e3:ee45e07709:-7fff:192.168.0.1</item> 

<item name="password" is-sensitive="true"><!-content suppressed ?</ 
item> 

<item name="protected- 
data">rO0ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVKkT2JqZWNOPjY9ps03VHACAARbAA 
11bmNvZGVkUGFyYW1lzdAACWOJLbABB1bmNyeXBOZWRDb250ZW50cOB+AAFMAA1wYXJhbX 
NBbGAdOABJMamF2YS9SYW5SnLINOcmluZztMAAdzZWFsQWxncOB+AAJ4cHVyAAJbQOqgzzF/ 
gGCFTgAgAASHAAAAAPMAOECIr9Z1iG+03BAgEKdXEAfgAEAAAAUMU/ 
SoFRkebvh2d5SqalF91ttjRYSlyyW5+/ 
FifOuDdYikYiDbOJb6607S0dPHjOzeVgubépt IvGqaEQOEjBjDkY+i4VOVjUSXS3a8fiX 
B8moMdPtLJ/GyE8QiwbT4xbkOy48i02k99F2vGmlenRpSP6dD31kZ13dpJ0mGgq2yL/ 
eFaynKyqnjkHLMexcqD8W1VooaR11k2RPk5vDYvC802bn220KKbOnSRM5Y1PS0iWzxo0 
JVcnVVyt OAANOOKVOABBOOKVXaXRoTUO1O0W5kREVT</item> 

<item name="responder-—dn">\PERIN-TAO\novel1\Provo\phb</item> 

<item name="auth-style sheet">process_template.xsl</item> 

<item name="response-style sheet">process_template.xsl</item> 

<item name="subject-name">Joe the Intern</item> 

<item name="url-base">https://192.168.0.1:8180</item> 

<item name="url">https://192.168.0.1:8180</item> 
</replacement-data> 


. The Web server verifies that the value of item responder-dn matches a responder-dn value 


contained in the protected data. If the value does not match, the Web server aborts the 
request. If the value does match, processing continues. 


. The Web server submits a <check-object-password> XDS request to Identity Manager on 


the Publisher channel to authenticate the user submitting the HTTP POST request. 


<nds dtdversion="1.0" ndsversion="8.6"> 
<source> 
<product build="20020606 0824" instance="Manual Task Service 
Driver" version="1.la">DirXML Manual Task Service Driver</product> 
<contact>Novell, Inc.</contact> 
</source> 
<input> 
<check-object-password dest-dn="\PERIN-TAO\novell\Provo\phb" 
event-id="chkpwd"> 


<password><!-- content suppressed --></password> 
</check-object-password> 
</input> 


</nds> 


. Identity Manager returns <status level=”success”>. If Identity Manager returns other 


than success, then the templates specified by the data item auth template and the style 
sheet specified by the data item auth stylesheet are used to construct a Web page that is 
returned as the result of the POST. 


. The Web server processes the post form.xml template with the process template.xsl 


style sheet to generate an XDS document. Replacement tokens are in bold. 


<nds> 
<input> 
<modify class-name="User" src-dn="not-applicable" event- 
id="wfmod"> 
<association>$association$</association> 
<modify-attr attr-name="roomNumber"> 


DirXML Driver for Manual Task Service Implementation Guide 


<remove-all-values/> 
<add-value> 
<value>$room-number$</value> 

</add-value> 

</modify-attr> 

</modify> 
</input> 
</nds> 


i. The Publisher submits the created XDS document to Identity Manager. 


<nds> 
<input> 
<modify class-name="User" src-dn="not-applicable" event- 
id="wfmod"> 
<association>45f0e3:ee45e07709:-7fff:192.168.0.1</association> 
<modify-attr attr-name="roomNumber"> 
<remove-all-values/> 
<add-value> 
<value>cubicle 1234</value> 
</add-value> 
</modify-attr> 
</modify> 
</input> 
</nds> 


j. Identity Manager returns a result document 


<nds dtdversion="1.1" ndsversion="8.6"> 
<source> 
<product version="2.0">Identity Manager</product> 
<contact>Novell, Inc.</contact> 
</source> 
<output> 
<status event-id="wfmod" level="success"></status> 
</output> 
</nds> 


k. The Web server adds the replacement data item post-status (and possibly the replacement 
data item post-status-message) to the replacement data document. The added data item is 
in bold: 


<replacement-data> 

<item name="room-number">cubicle 1234</item> 

<item name="template">post form.xml</item> 

<item name="response-template">post response.xml</item> 

<item name="auth-template">auth response.xml</item> 

<item name="association">45f0e3:ee45e07709:-7fff:192.168.0.1</item> 

<item name="password" is-sensitive="true”><!-content suppressed ?</ 
item> 

<item name="protected- 
data">rO0ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVKkT2JqZWNOP jY 9p SOBVHACAARbAA 
1lbmNvZGVkUGFyYW1zdAACWOJLbABBIbmNyeXBOZWRDb250ZW50cQB+AAFMAAlwYXJhbX 
NBbGdOABJMamF2YS9SYW5SnLINOcmluZztMAAdzZWFsQWxncOB+AAJ4cHVyAAJbQOqzzF/ 
gGCFTgAgAASHAAAAAPMAOECIr9Z1iG+03BAgEKdXEAfgAEAAAAUMU/ 
SoFRkebvh2d5SqalF91ttjRY5lyyW5+/ 
FifouDdYikYiDbOJb6607S0dPHjQzeVgu6pt IvGqaEQOEjBjDkY+i4VOVjUSXS3a8fiX 
B8moMdPt LJ/GyE8QiwbT4xbkOy48i02k99F2vGmlenRpSP6dD31kZ13dpJ0mGgq2yL/ 
eFaynKyqnjkHLMexcqD8W1VooaR11k2RPk5vDYvC802bn220KKbOnSRM5Y1PS0iWzxo0 
IVcnVVyt OAANOOKVOABBOOKVXaXRoTUO1OW5kREVT</item> 

<item name="responder-dn">\PERIN-TAO\novell\Provo\phb</item> 

<item name="auth-style sheet">process template.xsl</item> 
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<item name="response-style sheet">process_template.xsl</item> 
<item name="subject-name">Joe the Intern</item> 
<item name="url-base">https://192.168.0.1:8180</item> 
<item name="url">https://192.168.0.1:8180</item> 
<status event-id="" level="success"></status> 
<item name="post-status">success</item> 
</replacement-data> 


. The Web server processes the post response.xml template with the process template.xsl 
style sheet. Replacement tokens and action elements are in bold. 


<htm xmlns:form="http://www.novell.com/dirxml/manualtask/form"> 
<head> 
<title>Result of post for $subject-name$</title> 


</head> 

<body> 
<link href="novdocmain.css" rel="style sheet" type="text/css"/> 
<br/><br/><br/><br/> 


<table class="formtable" cellpadding="5" cellspacing="20" 
border="1" align="center"> 
<tr> 
<td> 
DirXML reported status = $post-status$ 
</td> 
</tr> 
<form:if-item-exists name="post-status-message"> 
<tr> 
<td> 
Status message was: $post-status-message$ 
</td> 
</tr> 
</form:if-item-exists> 
</table> 
</body> 
</html> 


. The resulting Web page is returned as the result of the HTTP POST. The second row of 
the table is not present because the post-status-message referred to by the <form:if-item- 
exists> element is not present in the replacement data document. 


<html> 
<head> 
<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
<title>Result of post for Joe the Intern</title> 


</head> 

<body> 
<link href="novdocmain.css" rel="style sheet" type="text/css"> 
<br><br><br><br> 


<table class="formtable" cellpadding="5" cellspacing="20" 
border="1" align="center"> 
<tr> 
<td> 
DirXML reported status = success 
</td> 
</tr> 
</table> 
</body> 
</html> 
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Custom Element Handlers for the Subscriber 
Channel 


The driver provides an extension mechanism for sending user notifications using methods other 
than the Simplified Mail Transport Protocol (SMTP). For example, a customer might have a need 
to send notifications using the Messaging Application Programming Interface (MAPI) rather than 
using SMTP. 


To use a mechanism other than SMTP for sending notifications, you must write a Java class to 
handle a custom XML element that is submitted on the driver’s Subscriber channel. 


The Java custom element handler must implement the 
com.novell.nds.dirxml.driver.manualtask.CommandHandler Java interface. The name of the 
custom element class is specified in the Additional Handlers item found in the Subscriber 
configuration parameters. 


When the Subscriber channel encounters a command element, it looks in its table of handlers. 
When it finds a handler that reports that it handles the command element, the command element 
is passed to the handler. The handler then performs any processing required. 


There are two built-in command element handlers in the driver: a handler for <mail> elements and 
a handler for <add> elements. 


The custom command element definition is up to the author of the custom handler. A reasonable 
place to start in designing the custom command element is the design of the <mail> element. 


The custom elements are created by policies on the Subscriber channel in the same fashion that the 
<mail> element is created. 


The documentation for com.novell.nds.dirxml.driver.manualtask.CommandHandler and the 
documentation for many utility and support classes are found in the javadocs that ship with the 
driver. The javadocs are found in the file named manual_task_docs.zip in the distribution image. 


Constructing URLs for Use with the Publisher Channel Web Server 


To securely use the driver’s Publisher channel web server, it is necessary to use utility classes to 
construct the URL that is to be included with a notification message. The 
com.novell.nds.dirxml.driver.manualtask. URLData is designed for this task. 


The sample code found in SampleCommandHandler.java illustrates this process. 


Constructing Message Documents using Stylesheets and Template 
Documents 


It is convenient to use the same method to construct documents that the SMTP handler uses, which 
is a combination of style sheets, template documents, and replacement data. To do this, you must 
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obtain the stylesheets and template documents, and invoke the style sheet processor 
programmatically. 


The sample code found in SampleCommandHandler.java illustrates this process. 


SampleCommandHandler.java 


Source code for a sample custom command handler is included with the driver distribution. The 
source code is found in the manual task docs.zip file in the distribution image. 


The handler is implemented in the 
com.novell.nds.dirxml.driver.manualtask.samples.SampleCommandHandler class. 


The sample handler simply generates a document using style sheets and templates and writes the 
resulting document to a file. 


Compiling the SampleCommandHandler Class 


You can use any Java 2 compiler to compile the SampleCommandHandler class. You must place 
nxsl jar, dirxml jar, collections.jar, and ManualTaskServiceBase.jar in the Java compiler classpath. 


Trying the SampleCommandHandler Class 
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Start by importing the Room Number sample configuration for the driver. 


Compile the SampleCommandHandler class and place the resulting class file in a .jar file. Place 
the jar file in the DirXML .jar file directory appropriate to the platform on which you are running 
the driver. 


Add the following XML element under the <subscriber-options> element found in the Driver 
Parameters XML section of the driver properties: 


<output-path display-name="Sample Output Path"></output-path> 


Edit the Driver Parameters. In the item labeled Sample Output Path, place a path to a directory in 
which the SampleCommandHandler will write its created documents. In the item labeled 
Additional Handlers, add the string 
com.novell.nds.dirxml.driver.manualtask.samples.SampleCommandHandler. 


Replace the Subscriber channel command transformation policy with CommandXform.xsl which 
is found in the same directory as the SampleCommandHandler.java file. 


Create a User object and add a manager reference to the User object. If the manager has an e-mail 
address value, then a <sample> command element is sent to the Subscriber and the 
SampleCommandHandler writes a file in the location you specified above. 
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Custom Servlets for the Publisher Channel 


The driver provides an extension mechanism through which additional functionality can be added 
to the Publisher channel Web server. Custom servlets can be loaded by the Publisher by specifying 
the name of the servlet classes in the Driver configuration item labeled Additional Servlets. 


Using the Publisher Channel 


If a custom servlet needs to submit data to Nsure™ Identity Manager, the servlet must use the 
driver’s Publisher channel. The com.novell.nds.dirxml.driver.manualtask.ServletRegistrar and 
com.novell.nds.dirxml.driver.manualtask.PublisherData classes are supplied to facilitate this. The 
sample code found in SampleServlet.java illustrates this process. 


Authentication 


A custom servlet must authenticate users that are submitting information. The sample code found 
in SampleServlet.java illustrates this process. However, the type of authentication performed using 
the <check-object-password> element does not check eDirectory™ rights. Changes submitted on 
the Publisher channel are allowed if the Driver object has rights to perform the changes, regardless 
of whether the user submitting the changes has rights or not. 


If you are using a URL generated by a command handler on the Subscriber channel, you must use 
the com.novell.nds.dirxml.driver.manualtask. URL Data class to validate the URL to ensure that 
the responder-dn data item has not been tampered with. See the javadocs for information on 
accomplishing this. 


SampleServlet.java 


Source code for a sample servlet is included with the driver distribution. The source code is found 
in the file manualtask_driver_docs.zip in the distribution image. 


The servlet is implemented in the 
com.novell.nds.dirxml.driver.manualtask.samples.SampleServlet class. 


The sample servlet accepts an HTTP GET request for any resource ending in .sample. The query 
string of the HTTP URL must contain a dest-dn item, an attr-name item, and a value item. 


The servlet authenticates the user, then submits a modify request to Identity Manager via the 
driver’s Publisher channel. 


Compiling the SampleServlet Class 


You can use any Java 2 compiler to compile the SampleServlet class. You must place nxsl.jar, 
dirxml jar, collections.jar, and ManualTaskServiceBase.jar in the Java compiler classpath. 
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Trying the SampleServlet Class 
Start by importing the Room Number sample configuration for the driver. 


Compile the SampleServlet class and place the resulting class file in a .jar file. Place the .jar file 
in the DirXML Jar file directory appropriate to the platform on which you are running the driver. 


Edit the Driver Parameters. In the item labeled Additional Servlets, add the string 
com.novell.nds.dirxml.driver.manualtask.samples.SampleServlet. 


Add Telephone Number to the Publisher channel filter. 


Submit the following URL in a browser (assuming the browser is running on the same machine as 
the driver): 


https:localhost:8180/1.sample?dest-dn=username.container&attr- 
name=Telephone%20Number&value=555-1212 


Replace username.container with the DN of a user in your tree. 
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Updates 


This section contains information about documentation content changes that have been made in 
this guide. 


The information is grouped according to the date the documentation updates were published. 


The documentation is provided on the Web in two formats: HTML and PDF. The HTML and PDF 
documentation are both kept up-to-date with the documentation changes listed in this section. 


If you need to know whether a copy of the PDF documentation you are using is the most recent, 
the PDF document contains the date it was published in the Legal Notices section immediately 
following the title page. 


The documentation was updated on the following dates: 
+ “January 2004” on page 59 
+ “May 27, 2004” on page 59 
* "August 3, 2004” on page 59 


January 2004 


As part of the release of the 1.0.1 version of the driver, the name was changed from DirXML 
Driver for Workflow to DirXML Driver for Manual Task Service. 


May 27, 2004 


Information was added in Chapter 1, “Overview,” on page 9 about upgrading the driver while 
preserving your existing files. 


August 3, 2004 


The following changes were made for the 1.0.2 version of the driver. 


¢ The driver implementation guide was converted to the same format as the other driver guides, 
with both HTML and PDF provided. 


+ “New Features” on page 9 was added. 


+ Upgrade information changed in Chapter 2, “Upgrading,” on page 17 to reflect improvements 
in the upgrade process. 


+ Chapter 3, “Installing,” on page 19 was added. 
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